{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Analysis notebook guidelines"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Jupyter notebooks can be a very useful tool for data analysis and measurement logging.\n",
    "Some of the main benefits are\n",
    "\n",
    "- Direct access to data and analysis code. The analysis is therefore reproducible.\n",
    "- Conversion of analysis notebooks into a website (ask Serwan for details).\n",
    "- Can be combined with version control, allowing tracking of changes.\n",
    "\n",
    "For everyone using SilQ/QCoDeS, the first point is especially true.\n",
    "Although Jupyter Notebook has several advantages when used as an analysis/logging tool, difficulties can arise.\n",
    "Speaking from personal experiences, the main struggle was how to organize the Jupyter Notebooks.\n",
    "There is a fine balance between having too many notebooks, and having too few notebooks that explode in size.\n",
    "Below we describe guidelines that we have found gave us good results.\n",
    "An added benefit of this structure is that it can be straightforwardly converted to a website."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Structure of an analysis notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Part 0. Initialization cell\n",
    "Each analysis notebook typically starts with a single initialization cell containing some code that loads all of the necessary packages/scripts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Part 1. Summary\n",
    "Next we have a header with caption Summary.  \n",
    "The summary should give a description of everything done in the notebook, and all the relevant findings/issues.  \n",
    "The idea is that later on, you can get a complete idea of everything measured in the notebook without having to look into the body of the notebook.\n",
    "\n",
    "The first cell should be a markdown cell where the first paragraph is a summary of the most important points of the notebook.  \n",
    "It is important to keep this as a single paragraph because it is extracted for the website.  \n",
    "When referring to a measurement in the summary, a hyperlink to the relevant measurement (sub)header should be used (see [bottom for info on hyperlinks](#guidelines)).  \n",
    "\n",
    "The first summary cell can also contain additional paragraphs, which should be used to expand on topics briefly described in the first paragraph, and to note other small findings not worthy of the first paragraph.  \n",
    "A good example is an issue you were facing and how you managed to solve it if at all.  \n",
    "Don't worry about making these paragraphs lengthy.\n",
    "\n",
    "After the first summary cell, subheaders should be used in which the most important data of the notebook should be displayed.  \n",
    "It is okay to copy code from other parts of the notebook, just be sure that the cell in the summary runs without having to execute cells further ahead.  \n",
    "Some effort should be put into making these figures clear (and pretty), as it should immediately clarify what the findings are.  \n",
    "These subheaders are also useful for joining data from multiple headers in the body of the analysis notebook, and performing some (minor) analysis on them.  \n",
    "As a general rule, measurements referred in the first paragraph should be displayed here."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Part 2. Measurements\n",
    "After the summary, the actual measurements are collected and analysed.  \n",
    "All measurements should be loaded chronologically, and grouped in a hierarchical structure.  \n",
    "The disadvantage of a chronological order is that switching between measurements will also be reflected in the analysis notebook, which may then lack a clear storyline.  \n",
    "\n",
    "### Hierarchical structuring of measurements\n",
    "Measurements should be grouped together using headers, subheaders, etc.  \n",
    "It is up to the person performing the analysis to decide at what level measurements should be grouped together.  \n",
    "The header level should generally be per topic.  \n",
    "Try to aim for notebooks containing ~4-10 headers, though it may of course vary per measurement set.  \n",
    "If you notice you need more than 10 headers, it may make sense to think if you can split the notebook into multiple notebooks.  \n",
    "Each header, subheader, etc. should have a title, followed by a line briefly summarizing the result.  \n",
    "Only add the most important information, and if possible, prepend with a green success or red fail specifying if the measurement(s) was successful. The following HTML can be used in markdown cells to create a success/fail signifier.\n",
    "- `**<span style=\"color:forestgreen\">Success</span>**`\n",
    "- `**<span style=\"color:red\">fail</span>**`\n",
    "\n",
    "Any more information should be placed in a markdown cell below the header.  \n",
    "After this, usually data is loaded and displayed, and text is added to describe the data and draw conclusions from it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='guidelines'></a>\n",
    "# Guidelines for analysis notebooks\n",
    "\n",
    "\n",
    "- Try to avoid multiple copies of analysis blocks, especially if it's long. Instead, create a function and place it in a script folder.\n",
    "- When creating a subsection, always use one level lower (i.e. not straight from header to subsubheader)\n",
    "- For the summary, try to create a storyline. Things don't necessarily have to be explained chronologically.\n",
    "- When the notebook is finished, ensure that it can run from start to finish by pressing Kernel -> Restart and run all\n",
    "- Do not write code cells that only output values. \n",
    "  For example. if you want to output a frequency from a fit, perform a `print` statement with some text explaining what is being output (and units!)\n",
    "- To create a hyperlink, first add an HTML tag at the destination markup cell (typically a header).\n",
    " - The HTML anchor tag must be written as: `<a id='your_tag_here'></a>`\n",
    " - To create a hyperlink in a markdown cell, simply include \"`[text with hyperlink](#your_tag_here)`\", with result: [text with hyperlink](#your_tag_here).\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}